---
title: Forgot Password
---

This page provides examples of how to create custom "forgot password" pages for your application. The forgot password functionality allows users to request a password reset email when they can't remember their current password.

## Custom page with `ForgotPassword` component

The `ForgotPassword` component provides a complete form for users to request a password reset email. When a user submits their email, Stack Auth will send them an email with a link to reset their password.

```tsx  
'use client';
import { ForgotPassword } from "@stackframe/stack";

export default function DefaultForgotPassword() {
  return <ForgotPassword />;
}
```

## Integration with Application Routing

To integrate the forgot password page with your application's routing:

1. Create a route for your forgot password page (e.g., `/forgot-password`)
2. Configure Stack Auth to use your custom route in your `stack/server.ts` file:

```tsx
export const stackServerApp = new StackServerApp({
  // ...
  urls: {
    forgotPassword: '/forgot-password',
  }
});
```

This ensures that links to the forgot password page will direct users to your custom implementation. When a user submits their email, Stack Auth will send them an email with a link to the password reset page configured in your application.


## Custom forgot password form

If you need more control over the forgot password process, you can build your own form. This approach allows you to customize the UI and error handling to match your application's design.

```tsx
'use client';

import { useStackApp } from "@stackframe/stack";
import { useState } from "react";

export default function CustomForgotPasswordForm() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState('');
  const [message, setMessage] = useState('');
  const app = useStackApp();

  const onSubmit = async () => {
    if (!email) {
      setError('Please enter your email address');
      setMessage('');
      return;
    }
    
    try {
      const result = await app.sendForgotPasswordEmail(email);
      if (result?.status === 'error') {
        if (result.error.code === 'user_not_found') {
          // For security reasons, don't reveal if a user exists or not
          setError('');
          setMessage('If an account exists with this email, a password reset link has been sent.');
        } else {
          setError(`Error: ${result.error.message}`);
          setMessage('');
        }
      } else {
        setError('');
        setMessage('Password reset email sent! Please check your inbox.');
      }
    } catch (err) {
      const message = err instanceof Error ? err.message : 'Unknown error';
      setError(`An unexpected error occurred: ${message}`);
      setMessage('');
    }
  };
  
  return (
    <form onSubmit={(e) => { e.preventDefault(); onSubmit(); }}>
      {error && <div>{error}</div>}
      {message ? (
        <div>{message}</div>
      ) : (
        <>
          <input
            type='email'
            placeholder="email@example.com"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
          />
          <button type='submit'>Reset Password</button>
        </>
      )}
    </form>
  ); 
}
```
